From 9595d440cf6c6d4fe010e71aabe888d4ff1fbd86 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Tue, 5 Jan 2021 08:20:36 -0500
Subject: [PATCH] docs: Flesh out Popup layout docs

We have nice illustrations for this, lets use them.
---
 .../{gtk => gdk}/images/popup-anchors.png     | Bin
 .../{gtk => gdk}/images/popup-flip.png        | Bin
 .../{gtk => gdk}/images/popup-slide.png       | Bin
 docs/reference/gdk/meson.build                |   3 ++
 .../{gtk/images => gdk}/popup-at.svg          |   0
 docs/reference/gtk/meson.build                |   4 ---
 gdk/gdkpopuplayout.c                          |  26 ++++++++++++++++++
 7 files changed, 29 insertions(+), 4 deletions(-)
 rename docs/reference/{gtk => gdk}/images/popup-anchors.png (100%)
 rename docs/reference/{gtk => gdk}/images/popup-flip.png (100%)
 rename docs/reference/{gtk => gdk}/images/popup-slide.png (100%)
 rename docs/reference/{gtk/images => gdk}/popup-at.svg (100%)

diff --git a/docs/reference/gtk/images/popup-anchors.png b/docs/reference/gdk/images/popup-anchors.png
similarity index 100%
rename from docs/reference/gtk/images/popup-anchors.png
rename to docs/reference/gdk/images/popup-anchors.png
diff --git a/docs/reference/gtk/images/popup-flip.png b/docs/reference/gdk/images/popup-flip.png
similarity index 100%
rename from docs/reference/gtk/images/popup-flip.png
rename to docs/reference/gdk/images/popup-flip.png
diff --git a/docs/reference/gtk/images/popup-slide.png b/docs/reference/gdk/images/popup-slide.png
similarity index 100%
rename from docs/reference/gtk/images/popup-slide.png
rename to docs/reference/gdk/images/popup-slide.png
diff --git a/docs/reference/gdk/meson.build b/docs/reference/gdk/meson.build
index c895131a3d..cdd018def9 100644
--- a/docs/reference/gdk/meson.build
+++ b/docs/reference/gdk/meson.build
@@ -146,6 +146,9 @@ images = [
   'images/nwse_resize_cursor.png',
   'images/zoom_in_cursor.png',
   'images/zoom_out_cursor.png',
+  'images/popup-anchors.png',
+  'images/popup-flip.png',
+  'images/popup-slide.png',
 ]
 
 src_dir = [ gdkinc ]
diff --git a/docs/reference/gtk/images/popup-at.svg b/docs/reference/gdk/popup-at.svg
similarity index 100%
rename from docs/reference/gtk/images/popup-at.svg
rename to docs/reference/gdk/popup-at.svg
diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index cdd53d61e8..a2e28b586f 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -413,10 +413,6 @@ images = [
   'images/password-entry.png',
   'images/picture.png',
   'images/popover.png',
-  'images/popup-anchors.png',
-  'images/popup-at.svg',
-  'images/popup-flip.png',
-  'images/popup-slide.png',
   'images/printdialog.png',
   'images/progressbar.png',
   'images/right-center.png',
diff --git a/gdk/gdkpopuplayout.c b/gdk/gdkpopuplayout.c
index 0542bec811..bff14a935c 100644
--- a/gdk/gdkpopuplayout.c
+++ b/gdk/gdkpopuplayout.c
@@ -30,6 +30,32 @@
  * Popups are positioned relative to their parent surface.
  * The GdkPopupLayout struct contains information that is
  * necessary to do so.
+ *
+ * The positioning requires a negotiation with the windowing system,
+ * since it depends on external constraints, such as the position of
+ * the parent surface, and the screen dimensions.
+ *
+ * The basic ingredients are a rectangle on the parent surface,
+ * and the anchor on both that rectangle and the popup. The anchors
+ * specify a side or corner to place next to each other.
+ *
+ * ![Popup anchors](popup-anchors.png)
+ *
+ * For cases where placing the anchors next to each other would make
+ * the popup extend offscreen, the layout includes some hints for how
+ * to resolve this problem. The hints may suggest to flip the anchor
+ * position to the other side, or to 'slide' the popup along a side,
+ * or to resize it.
+ *
+ * ![Flipping popups](popup-flip.png)
+ *
+ * ![Sliding popups](popup-slide.png)
+ *
+ * These hints may be combined, but it is ultimatively up to the windowing
+ * system to determine the position and size of the popup. You can learn
+ * about the result by calling gdk_popup_get_position_x(),
+ * gdk_popup_get_position_y(), gdk_popup_get_rect_anchor() and
+ * gdk_popup_get_surface_anchor() after the popup has been presented.
  */
 
 struct _GdkPopupLayout
-- 
2.30.2